home *** CD-ROM | disk | FTP | other *** search
/ Developer CD Series 1997 October: Mac OS SDK / Dev.CD Oct 97 SDK1.toast / Development Kits (Disc 1) / Interfaces&Libraries / Universal / Interfaces / CIncludes / QD3DCamera.h < prev    next >
Encoding:
C/C++ Source or Header  |  1997-08-12  |  11.0 KB  |  370 lines  |  [TEXT/MPS ]
  1. /******************************************************************************
  2.  **                                                                             **
  3.  **     Module:        QD3DCamera.h                                             **
  4.  **                                                                          **
  5.  **                                                                          **
  6.  **     Purpose:     Generic camera routines                                      **
  7.  **                                                                          **
  8.  **                                                                          **
  9.  **                                                                          **
  10.  **     Copyright (C) 1991-1997 Apple Computer, Inc. All rights reserved.     **
  11.  **                                                                          **
  12.  **                                                                          **
  13.  *****************************************************************************/
  14. #ifndef QD3DCamera_h
  15. #define QD3DCamera_h
  16.  
  17. #include "QD3D.h"
  18.  
  19. #if defined(PRAGMA_ONCE) && PRAGMA_ONCE
  20.     #pragma once
  21. #endif  /*  PRAGMA_ONCE  */
  22.  
  23. #if defined(OS_MACINTOSH) && OS_MACINTOSH
  24.  
  25. #if defined(__xlc__) || defined(__XLC121__)
  26.     #pragma options enum=int
  27.     #pragma options align=power
  28. #elif defined(__MWERKS__)
  29.     #pragma enumsalwaysint on
  30.     #pragma options align=native
  31. #elif defined(__MRC__) || defined(__SC__)
  32.     #if __option(pack_enums)
  33.         #define PRAGMA_ENUM_RESET_QD3DCAMERA 1
  34.     #endif
  35.     #pragma options(!pack_enums)
  36.     #pragma options align=power
  37. #endif
  38.  
  39. #endif  /* OS_MACINTOSH */
  40.  
  41. #ifdef __cplusplus
  42. extern "C" {
  43. #endif    /* __cplusplus */
  44.  
  45.  
  46. /******************************************************************************
  47.  **                                                                             **
  48.  **                            Data Structure Definitions                         **
  49.  **                                                                             **
  50.  *****************************************************************************/
  51. /*
  52.  *  The placement of the camera.
  53.  */
  54. typedef struct TQ3CameraPlacement{
  55.     TQ3Point3D        cameraLocation;        /*  Location point of the camera     */
  56.     TQ3Point3D        pointOfInterest;    /*  Point of interest                 */
  57.     TQ3Vector3D        upVector;            /*  "up" vector                     */
  58. } TQ3CameraPlacement;
  59.  
  60.  
  61. /*
  62.  *  The range of the camera.
  63.  */
  64. typedef struct TQ3CameraRange {
  65.     float    hither;        /*  Hither plane, measured from "from" towards "to"    */
  66.     float    yon;        /*  Yon  plane, measured from "from" towards "to"     */
  67. } TQ3CameraRange;
  68.  
  69.  
  70. /*
  71.  *  Viewport specification.  Origin is (-1, 1), and corresponds to the 
  72.  *  upper left-hand corner; width and height maximum is (2.0, 2.0),
  73.  *  corresponding to the lower left-hand corner of the window.  The
  74.  *  TQ3Viewport specifies a part of the viewPlane that gets displayed 
  75.  *    on the window that is to be drawn.
  76.  *  Normally, it is set with an origin of (-1.0, 1.0), and a width and
  77.  *  height of both 2.0, specifying that the entire window is to be
  78.  *  drawn.  If, for example, an exposure event of the window exposed
  79.  *  the right half of the window, you would set the origin to (0, 1),
  80.  *  and the width and height to (1.0) and (2.0), respectively.
  81.  *
  82.  */
  83. typedef struct TQ3CameraViewPort {
  84.     TQ3Point2D        origin;
  85.     float            width;
  86.     float            height;
  87. } TQ3CameraViewPort;
  88.  
  89.  
  90. typedef struct TQ3CameraData {
  91.     TQ3CameraPlacement    placement;
  92.     TQ3CameraRange        range;
  93.     TQ3CameraViewPort    viewPort;
  94. } TQ3CameraData;
  95.  
  96.  
  97. /*
  98.  *  An orthographic camera.
  99.  *
  100.  *  The lens characteristics are set with the dimensions of a
  101.  *  rectangular viewPort in the frame of the camera.
  102.  */
  103. typedef struct TQ3OrthographicCameraData {
  104.     TQ3CameraData        cameraData;
  105.     float                left;
  106.     float                top;
  107.     float                right;
  108.     float                bottom;
  109. } TQ3OrthographicCameraData;
  110.  
  111. /*
  112.  *  A perspective camera specified in terms of an arbitrary view plane.
  113.  *
  114.  *  This is most useful when setting the camera to look at a particular
  115.  *  object.  The viewPlane is set to distance from the camera to the object.
  116.  *  The halfWidth is set to half the width of the cross section of the object,
  117.  *  and the halfHeight equal to the halfWidth divided by the aspect ratio
  118.  *  of the viewPort.
  119.  * 
  120.  *  This is the only perspective camera with specifications for off-axis
  121.  *  viewing, which is desirable for scrolling.
  122.  */
  123. typedef struct TQ3ViewPlaneCameraData {
  124.     TQ3CameraData        cameraData;
  125.     float                viewPlane;
  126.     float                halfWidthAtViewPlane;
  127.     float                halfHeightAtViewPlane;
  128.     float                centerXOnViewPlane;
  129.     float                centerYOnViewPlane;
  130. } TQ3ViewPlaneCameraData;
  131.  
  132. /*
  133.  *    A view angle aspect camera is a perspective camera specified in 
  134.  *    terms of the minimum view angle and the aspect ratio of X to Y.
  135.  *
  136.  */
  137. typedef struct TQ3ViewAngleAspectCameraData {
  138.     TQ3CameraData        cameraData;
  139.     float                fov;
  140.     float                aspectRatioXToY;
  141. } TQ3ViewAngleAspectCameraData;
  142.  
  143.  
  144. /******************************************************************************
  145.  **                                                                             **
  146.  **                            Generic Camera routines                             **
  147.  **                                                                             **
  148.  *****************************************************************************/
  149.  
  150.  
  151. QD3D_EXPORT TQ3ObjectType QD3D_CALL Q3Camera_GetType(
  152.     TQ3CameraObject                camera);
  153.  
  154. QD3D_EXPORT TQ3Status QD3D_CALL Q3Camera_SetData(
  155.     TQ3CameraObject                camera,
  156.     const TQ3CameraData            *cameraData);
  157.  
  158. QD3D_EXPORT TQ3Status QD3D_CALL Q3Camera_GetData(
  159.     TQ3CameraObject                camera,
  160.     TQ3CameraData                *cameraData);
  161.     
  162. QD3D_EXPORT TQ3Status QD3D_CALL Q3Camera_SetPlacement(
  163.     TQ3CameraObject                camera,
  164.     const TQ3CameraPlacement    *placement);
  165.     
  166. QD3D_EXPORT TQ3Status QD3D_CALL Q3Camera_GetPlacement(
  167.     TQ3CameraObject                camera,
  168.     TQ3CameraPlacement            *placement);
  169.     
  170. QD3D_EXPORT TQ3Status QD3D_CALL Q3Camera_SetRange(
  171.     TQ3CameraObject                camera,
  172.     const TQ3CameraRange        *range);
  173.  
  174. QD3D_EXPORT TQ3Status QD3D_CALL Q3Camera_GetRange(
  175.     TQ3CameraObject                camera,
  176.     TQ3CameraRange                *range);
  177.  
  178. QD3D_EXPORT TQ3Status QD3D_CALL Q3Camera_SetViewPort(
  179.     TQ3CameraObject                camera,
  180.     const TQ3CameraViewPort        *viewPort);
  181.  
  182. QD3D_EXPORT TQ3Status QD3D_CALL Q3Camera_GetViewPort(
  183.     TQ3CameraObject                camera,
  184.     TQ3CameraViewPort            *viewPort);
  185.  
  186. QD3D_EXPORT TQ3Status QD3D_CALL Q3Camera_GetWorldToView( 
  187.     TQ3CameraObject                camera,
  188.     TQ3Matrix4x4                *worldToView);
  189.  
  190. QD3D_EXPORT TQ3Status QD3D_CALL Q3Camera_GetWorldToFrustum( 
  191.     TQ3CameraObject                camera,
  192.     TQ3Matrix4x4                *worldToFrustum);
  193.  
  194. QD3D_EXPORT TQ3Status QD3D_CALL Q3Camera_GetViewToFrustum(
  195.     TQ3CameraObject                camera,
  196.     TQ3Matrix4x4                *viewToFrustum);
  197.  
  198.  
  199. /******************************************************************************
  200.  **                                                                             **
  201.  **                            Specific Camera Routines                          **
  202.  **                                                                             **
  203.  *****************************************************************************/
  204.  
  205. /******************************************************************************
  206.  **                                                                             **
  207.  **                            Orthographic Camera                                  **
  208.  **                                                                             **
  209.  *****************************************************************************/
  210.  
  211. QD3D_EXPORT TQ3CameraObject QD3D_CALL Q3OrthographicCamera_New(
  212.     const TQ3OrthographicCameraData    *orthographicData);
  213.  
  214. QD3D_EXPORT TQ3Status QD3D_CALL Q3OrthographicCamera_GetData(
  215.     TQ3CameraObject                    camera,
  216.     TQ3OrthographicCameraData        *cameraData);
  217.  
  218. QD3D_EXPORT TQ3Status QD3D_CALL Q3OrthographicCamera_SetData(
  219.     TQ3CameraObject                    camera,
  220.     const TQ3OrthographicCameraData    *cameraData);
  221.  
  222. QD3D_EXPORT TQ3Status QD3D_CALL Q3OrthographicCamera_SetLeft(
  223.     TQ3CameraObject                    camera,
  224.     float                            left);
  225.     
  226. QD3D_EXPORT TQ3Status QD3D_CALL Q3OrthographicCamera_GetLeft(
  227.     TQ3CameraObject                    camera,
  228.     float                            *left);
  229.  
  230. QD3D_EXPORT TQ3Status QD3D_CALL Q3OrthographicCamera_SetTop(
  231.     TQ3CameraObject                    camera,
  232.     float                            top);
  233.     
  234. QD3D_EXPORT TQ3Status QD3D_CALL Q3OrthographicCamera_GetTop(
  235.     TQ3CameraObject                    camera,
  236.     float                            *top);
  237.  
  238. QD3D_EXPORT TQ3Status QD3D_CALL Q3OrthographicCamera_SetRight(
  239.     TQ3CameraObject                    camera,
  240.     float                            right);
  241.     
  242. QD3D_EXPORT TQ3Status QD3D_CALL Q3OrthographicCamera_GetRight(
  243.     TQ3CameraObject                    camera,
  244.     float                            *right);
  245.  
  246. QD3D_EXPORT TQ3Status QD3D_CALL Q3OrthographicCamera_SetBottom(
  247.     TQ3CameraObject                    camera,
  248.     float                            bottom);
  249.     
  250. QD3D_EXPORT TQ3Status QD3D_CALL Q3OrthographicCamera_GetBottom(
  251.     TQ3CameraObject                    camera,
  252.     float                            *bottom);
  253.  
  254.  
  255. /******************************************************************************
  256.  **                                                                             **
  257.  **                            ViewPlane Camera                                  **
  258.  **                                                                             **
  259.  *****************************************************************************/
  260.  
  261. QD3D_EXPORT TQ3CameraObject QD3D_CALL Q3ViewPlaneCamera_New(
  262.     const TQ3ViewPlaneCameraData    *cameraData);
  263.     
  264. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewPlaneCamera_GetData(
  265.     TQ3CameraObject                    camera,
  266.     TQ3ViewPlaneCameraData            *cameraData);
  267.  
  268. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewPlaneCamera_SetData(
  269.     TQ3CameraObject                    camera,
  270.     const TQ3ViewPlaneCameraData    *cameraData);
  271.  
  272. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewPlaneCamera_SetViewPlane(
  273.     TQ3CameraObject                    camera,
  274.     float                            viewPlane);
  275.     
  276. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewPlaneCamera_GetViewPlane(
  277.     TQ3CameraObject                    camera,
  278.     float                            *viewPlane);
  279.  
  280. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewPlaneCamera_SetHalfWidth(
  281.     TQ3CameraObject                    camera,
  282.     float                            halfWidthAtViewPlane);
  283.  
  284. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewPlaneCamera_GetHalfWidth(
  285.     TQ3CameraObject                    camera,
  286.     float                            *halfWidthAtViewPlane);
  287.  
  288. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewPlaneCamera_SetHalfHeight(
  289.     TQ3CameraObject                    camera,
  290.     float                            halfHeightAtViewPlane);
  291.  
  292. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewPlaneCamera_GetHalfHeight(
  293.     TQ3CameraObject                    camera,
  294.     float                            *halfHeightAtViewPlane);
  295.     
  296. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewPlaneCamera_SetCenterX(
  297.     TQ3CameraObject                    camera,
  298.     float                            centerXOnViewPlane);
  299.     
  300. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewPlaneCamera_GetCenterX(
  301.     TQ3CameraObject                    camera,
  302.     float                            *centerXOnViewPlane);
  303.     
  304. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewPlaneCamera_SetCenterY(
  305.     TQ3CameraObject                    camera,
  306.     float                            centerYOnViewPlane);
  307.     
  308. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewPlaneCamera_GetCenterY(
  309.     TQ3CameraObject                    camera,
  310.     float                            *centerYOnViewPlane);
  311.  
  312.  
  313. /******************************************************************************
  314.  **                                                                             **
  315.  **                            View Angle Aspect Camera                          **
  316.  **                                                                             **
  317.  *****************************************************************************/
  318.  
  319. QD3D_EXPORT TQ3CameraObject QD3D_CALL Q3ViewAngleAspectCamera_New(
  320.     const TQ3ViewAngleAspectCameraData    *cameraData);
  321.  
  322. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewAngleAspectCamera_SetData(
  323.     TQ3CameraObject                        camera,
  324.     const TQ3ViewAngleAspectCameraData    *cameraData);
  325.     
  326. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewAngleAspectCamera_GetData(
  327.     TQ3CameraObject                        camera,
  328.     TQ3ViewAngleAspectCameraData        *cameraData);
  329.  
  330. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewAngleAspectCamera_SetFOV(
  331.     TQ3CameraObject                        camera,
  332.     float                                fov);
  333.  
  334. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewAngleAspectCamera_GetFOV(
  335.     TQ3CameraObject                        camera,
  336.     float                                *fov);
  337.  
  338. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewAngleAspectCamera_SetAspectRatio(
  339.     TQ3CameraObject                        camera,
  340.     float                                aspectRatioXToY);
  341.     
  342. QD3D_EXPORT TQ3Status QD3D_CALL Q3ViewAngleAspectCamera_GetAspectRatio(
  343.     TQ3CameraObject                        camera,
  344.     float                                *aspectRatioXToY);
  345.  
  346.  
  347. #ifdef __cplusplus
  348. }
  349. #endif    /* __cplusplus */
  350.  
  351. #if defined(OS_MACINTOSH) && OS_MACINTOSH
  352.  
  353. #if defined(__xlc__) || defined(__XLC121__)
  354.     #pragma options enum=reset
  355.     #pragma options align=reset
  356. #elif defined(__MWERKS__)
  357.     #pragma enumsalwaysint reset
  358.     #pragma options align=reset
  359. #elif defined(__MRC__) || defined(__SC__)
  360.     #if PRAGMA_ENUM_RESET_QD3DCAMERA
  361.         #pragma options(pack_enums)
  362.         #undef PRAGMA_ENUM_RESET_QD3DCAMERA
  363.     #endif
  364.     #pragma options align=reset
  365. #endif
  366.  
  367. #endif  /* OS_MACINTOSH */
  368.  
  369. #endif  /*  QD3DCamera_h  */
  370.